
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

    <title>Writing a monitors test action &#8212; LAVA 2024.05 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    <link rel="shortcut icon" href="_static/favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Writing an interactive test action" href="interactive.html" />
    <link rel="prev" title="Publishing artifacts" href="publishing-artifacts.html" />
    <link rel="canonical" href="https://docs.lavasoftware.org/lava/monitors.html" />
  
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>


  </head><body>

  <div id="navbar" class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="index.html"><span><img src="_static/lava.png"></span>
          LAVA</a>
        <span class="navbar-text navbar-version pull-left"><b>2024.05</b></span>
      </div>

        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            
                <li><a href="genindex.html">Index</a></li>
                <li><a href="contents.html">Contents</a></li>
            
            
              <li class="dropdown globaltoc-container">
  <a role="button"
     id="dLabelGlobalToc"
     data-toggle="dropdown"
     data-target="#"
     href="index.html">Site <b class="caret"></b></a>
  <ul class="dropdown-menu globaltoc"
      role="menu"
      aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction to LAVA</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="contents.html">Contents</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary of terms</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="support.html">Getting support</a></li>
</ul>
</ul>
</li>
              
                <li class="dropdown">
  <a role="button"
     id="dLabelLocalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Page <b class="caret"></b></a>
  <ul class="dropdown-menu localtoc"
      role="menu"
      aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Writing a monitors test action</a><ul>
<li><a class="reference internal" href="#restrictions">Restrictions</a></li>
<li><a class="reference internal" href="#example-test-monitors-job">Example test monitors job</a></li>
</ul>
</li>
</ul>
</ul>
</li>
              
            
            
              
                
  <li>
    <a href="publishing-artifacts.html" title="Previous Chapter: Publishing artifacts"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">&laquo; Publishing artifacts</span>
    </a>
  </li>
  <li>
    <a href="interactive.html" title="Next Chapter: Writing an interactive test action"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Writing an in... &raquo;</span>
    </a>
  </li>
              
            
            
            
            
              <li class="hidden-sm"></li>
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
    <div class="body col-md-12 content" role="main">
      
  <section id="writing-a-monitors-test-action">
<span id="writing-tests-monitor"></span><span id="index-0"></span><h1>Writing a monitors test action<a class="headerlink" href="#writing-a-monitors-test-action" title="Permalink to this heading">¶</a></h1>
<div class="admonition seealso">
<p class="admonition-title">See also</p>
<p><a class="reference internal" href="actions-test.html#monitor-test-action"><span class="std std-ref">Monitors</span></a> and <a class="reference internal" href="developing-tests.html#test-developer"><span class="std std-ref">Writing Tests</span></a></p>
</div>
<p><a class="reference internal" href="writing-tests.html#writing-tests-1-0"><span class="std std-ref">Writing a Lava-Test Test Definition 1.0</span></a> involves adding an overlay of POSIX scripts to
the DUT but some devices cannot support an overlay. The <code class="docutils literal notranslate"><span class="pre">monitors</span></code>
test action supports IoT devices using pattern matching against
non-interactive output streams. As with <a class="reference internal" href="lava_test_shell.html#parse-patterns-1-0-deprecated"><span class="std std-ref">pattern matching  in the
Lava-Test Test Definition 1.0</span></a>, this
can be difficult at times.</p>
<p>The IoT application needs to be specially written to create output
which is compatible with automation. Test actions for IoT devices tend
to be short and specific to one dedicated application executing on the
DUT. Applications need to be written to emit a <code class="docutils literal notranslate"><span class="pre">START</span></code> and <code class="docutils literal notranslate"><span class="pre">STOP</span></code>
message which have to be unique across all test job output, not just
the test action. Test writers then need to correlate specific pattern
match expressions in the test job with the behavior of the application
deployed in that test job. This puts the work of creating a parser into
the hands of the writers of the test application and can thus interfere
with development of the test application.</p>
<section id="restrictions">
<h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this heading">¶</a></h2>
<p>Test jobs using Monitors must:</p>
<ul class="simple">
<li><p>Use carefully designed applications which are designed to
automatically execute after boot.</p></li>
<li><p>Emit a unique start string:</p>
<ul>
<li><p>Only once per boot operation.</p></li>
<li><p>Before any test operation starts.</p></li>
</ul>
</li>
<li><p>Emit a unique end string:</p>
<ul>
<li><p>Only once per boot operation.</p></li>
<li><p>After all test operations have completed.</p></li>
</ul>
</li>
<li><p>Provide a regular expression which matches all expected test output
and maps the output to results without leading to excessively long
test case names.</p></li>
<li><p>start and end strings will match part of a line but make sure that
each string is long enough that it can only match once per boot.</p></li>
</ul>
<p>If start does not match, the job will timeout with no results.</p>
<p>If end does not match, the job will timeout but the results (of the
current boot) will already have been reported.</p>
</section>
<section id="example-test-monitors-job">
<span id="example-monitors-job"></span><h2>Example test monitors job<a class="headerlink" href="#example-test-monitors-job" title="Permalink to this heading">¶</a></h2>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="linenos"> 1</span><span class="c1"># Zephyr JOB definition for IoT</span>
<span class="linenos"> 2</span><span class="nt">device_type</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">frdm-kw41z</span>
<span class="linenos"> 3</span><span class="nt">job_name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">frdm-kw41z zephyr IoT example</span>
<span class="linenos"> 4</span>
<span class="linenos"> 5</span><span class="nt">timeouts</span><span class="p">:</span>
<span class="linenos"> 6</span><span class="w">  </span><span class="nt">job</span><span class="p">:</span>
<span class="linenos"> 7</span><span class="w">    </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
<span class="linenos"> 8</span><span class="w">  </span><span class="nt">action</span><span class="p">:</span>
<span class="linenos"> 9</span><span class="w">    </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</span>
<span class="linenos">10</span><span class="w">  </span><span class="nt">actions</span><span class="p">:</span>
<span class="linenos">11</span><span class="w">    </span><span class="nt">wait-usb-device</span><span class="p">:</span>
<span class="linenos">12</span><span class="w">      </span><span class="nt">seconds</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">40</span>
<span class="linenos">13</span>
<span class="linenos">14</span><span class="nt">priority</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">medium</span>
<span class="linenos">15</span><span class="nt">visibility</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">public</span>
<span class="linenos">16</span>
<span class="linenos">17</span><span class="nt">actions</span><span class="p">:</span>
<span class="linenos">18</span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">deploy</span><span class="p">:</span>
<span class="linenos">19</span><span class="w">    </span><span class="nt">timeout</span><span class="p">:</span>
<span class="linenos">20</span><span class="w">      </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">3</span>
<span class="linenos">21</span><span class="w">    </span><span class="nt">to</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tmpfs</span>
<span class="linenos">22</span><span class="w">    </span><span class="nt">images</span><span class="p">:</span>
<span class="linenos">23</span><span class="w">        </span><span class="nt">zephyr</span><span class="p">:</span>
<span class="linenos">24</span><span class="w">            </span><span class="nt">url</span><span class="p">:</span><span class="w">  </span><span class="l l-Scalar l-Scalar-Plain">http://images.validation.linaro.org/snapshots.linaro.org/components/kernel/zephyr/master/zephyr/frdm_kw41z/737/tests/kernel/libs/test/zephyr.bin</span>
<span class="linenos">25</span>
<span class="linenos">26</span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">boot</span><span class="p">:</span>
<span class="linenos">27</span><span class="w">    </span><span class="nt">method</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">pyocd</span>
<span class="linenos">28</span><span class="w">    </span><span class="nt">timeout</span><span class="p">:</span>
<span class="linenos">29</span><span class="w">      </span><span class="nt">minutes</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">10</span>
<span class="linenos">30</span>
<span class="linenos">31</span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">test</span><span class="p">:</span>
<span class="hll"><span class="linenos">32</span><span class="w">    </span><span class="nt">monitors</span><span class="p">:</span>
</span><span class="hll"><span class="linenos">33</span><span class="w">    </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">tests</span>
</span><span class="hll"><span class="linenos">34</span><span class="w">      </span><span class="nt">start</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">BOOTING ZEPHYR</span>
</span><span class="hll"><span class="linenos">35</span><span class="w">      </span><span class="nt">end</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">PROJECT EXECUTION SUCCESSFUL</span>
</span><span class="hll"><span class="linenos">36</span><span class="w">      </span><span class="nt">pattern</span><span class="p">:</span><span class="w"> </span><span class="s">&#39;(?P&lt;test_case_id&gt;.*)</span><span class="nv"> </span><span class="s">(?P&lt;measurement&gt;.*)</span><span class="nv"> </span><span class="s">tcs</span><span class="nv"> </span><span class="s">=</span><span class="nv"> </span><span class="s">[0-9]*</span><span class="nv"> </span><span class="s">nsec&#39;</span>
</span><span class="hll"><span class="linenos">37</span><span class="w">      </span><span class="nt">fixupdict</span><span class="p">:</span>
</span><span class="hll"><span class="linenos">38</span><span class="w">        </span><span class="nt">PASS</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">pass</span>
</span><span class="hll"><span class="linenos">39</span><span class="w">        </span><span class="nt">FAIL</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">fail</span>
</span></pre></div>
</div>
<p>Download or view example test monitors job:
<a class="reference external" href="examples/test-jobs/frdm-kw41z-zephyr.yaml">examples/test-jobs/frdm-kw41z-zephyr.yaml</a></p>
</section>
</section>


    </div>
      
  </div>
</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
    </p>
    <p>
        &copy; Copyright 2010-2019, Linaro Limited.<br/>
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
    </p>
  </div>
</footer>
  </body>
</html>